feat(bridge): add KYC tier ceiling error code (ENG-354)#394
Merged
islandbitcoin merged 2 commits intoJun 8, 2026
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new Bridge-specific GraphQL error code intended to distinguish “KYC tier ceiling exceeded” withdrawal failures from generic Bridge API errors, and documents/tests the mapping.
Changes:
- Introduced
BridgeKycTierCeilingExceededErrorplus detection logic inmapBridgeHttpErrorfor Bridge 400/422 responses. - Mapped
BridgeKycTierCeilingExceededErrorto the new GraphQL error codeBRIDGE_KYC_TIER_CEILING_EXCEEDED. - Updated Bridge integration docs and extended unit tests for mapping/detection.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
src/services/bridge/errors.ts |
Adds a new domain error and attempts to detect it from Bridge HTTP response bodies. |
src/graphql/error-map.ts |
Maps the new domain error to a distinct GraphQL error code. |
docs/bridge-integration/API.md |
Documents the new error code in the Bridge error table. |
test/flash/unit/graphql/bridge-error-map.spec.ts |
Adds unit tests for the new GraphQL mapping and mapBridgeHttpError detection heuristics. |
Comments suppressed due to low confidence (1)
src/services/bridge/errors.ts:151
mapBridgeHttpErroris not referenced anywhere insrc/(it only appears in this file and the new unit test), so the new KYC-tier ceiling detection and error class mapping will never be produced by runtime Bridge requests. As a result, withdrawals that exceed the KYC tier ceiling will still surface as genericBridgeApiError/BRIDGE_API_ERRORunless Bridge request error handling is updated to call this mapper (e.g., in the Bridge client request wrapper or in the withdrawal orchestration catch path).
export const mapBridgeHttpError = (
statusCode: number,
response?: unknown,
): BridgeError => {
// Bridge returns 422/400 with a specific error type for KYC tier ceiling violations.
if (
(statusCode === 422 || statusCode === 400) &&
typeof response === "object" &&
response !== null
) {
const resp = response as Record<string, unknown>
const errorObj = (resp.error ?? resp) as Record<string, unknown> | undefined
const errorType = String(errorObj?.type ?? "").toLowerCase()
const errorMessage = String(errorObj?.message ?? resp?.message ?? "").toLowerCase()
if (
errorType.includes("kyc_tier_limit") ||
errorType.includes("kyc_limit") ||
errorType.includes("tier_ceiling") ||
(errorMessage.includes("kyc") &&
(errorMessage.includes("limit") ||
errorMessage.includes("ceiling") ||
errorMessage.includes("tier")))
) {
const message = typeof resp.message === "string" ? resp.message : undefined
return new BridgeKycTierCeilingExceededError(message)
}
}
switch (statusCode) {
case 404:
return new BridgeCustomerNotFoundError()
case 429:
return new BridgeRateLimitError()
case 408:
return new BridgeTimeoutError()
default:
return new BridgeApiError("Bridge API error", statusCode, response)
}
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+137
to
+138
| const message = typeof resp.message === "string" ? resp.message : undefined | ||
| return new BridgeKycTierCeilingExceededError(message) |
… eng-354/kyc-tier-ceiling-error # Conflicts: # src/services/bridge/errors.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a distinct
BRIDGE_KYC_TIER_CEILING_EXCEEDEDGraphQL error code for when Bridge rejects a withdrawal because the amount exceeds the user's KYC-tier cap.Changes
src/services/bridge/errors.ts: AddedBridgeKycTierCeilingExceededErrorclass + detection inmapBridgeHttpErrorfor Bridge API 422/400 responses containing KYC tier ceiling errorssrc/graphql/error-map.ts: MappedBridgeKycTierCeilingExceededError→BRIDGE_KYC_TIER_CEILING_EXCEEDEDdocs/bridge-integration/API.md: Added error code to the tabletest/flash/unit/graphql/bridge-error-map.spec.ts: Added GQL mapping test for the new error + 5mapBridgeHttpErrordetection testsVerification
yarn check:sdlclean